#region (c) 2014 THN Solutions LLC. - All rights reserved
/*
THN DATA ABSTRACTION LAYER version 1

Copyright (c) 2014, THN Solutions LLC. ( www.ThnSolutions.com )
Author: Nguyễn, M. Hải                 ( www.Minh-Hai.com     )
All rights reserved.

This library is dual-licensed.
  + For commercial software, please obtain a commercial license from THN Solutions LLC.

  + For free software, this library is licensed under GPL version 3. A summary of GPLv3 is
    listed below. You should also find a copy of GPLv3 as file License_GPLv3.txt included
	with the source-code files.

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License version 3 as published by
    the Free Software Foundation  of the License.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/
#endregion

#region Using directives
using System;
using System.Collections;
using Thn.Application;
using Thn.Data.Query;
#endregion

namespace Thn.Data
{
    /// <summary>
    /// Abstract interface of a data storage source.
    /// <para>A database deals with primitive objects and transactions. It does not handle relationship, concurrency and complex transaction matters</para>
    /// </summary>
    public interface IDatabase : IQueryProcessor
    {
        #region I/O
        /// <summary>
        /// Prepare connection to database
        /// </summary>
        /// <param name="parameters">connection string</param>
        void Initialize(string parameters);

        /// <summary>
        /// Refresh/load data, if neccessary
        /// </summary>
        void Refresh();

        /// <summary>
        /// Persist changes to database, if still buffered
        /// </summary>
        void Flush();

        /// <summary>
        /// Close connection to the underlying database, if neccessary
        /// </summary>
        void Close();
        #endregion

        #region Transaction
        /// <summary>
        /// Start a new transaction.
        /// </summary>
        /// <returns>The transaction context specific to database</returns>
        object BeginTransaction();

        /// <summary>
        /// Execute task(s) contained in this transaction and persist changes to database
        /// </summary>
        /// <param name="transactionContext">The transaction context specific to database</param>
        void CommitTransaction(object transactionContext);

        /// <summary>
        /// Abandon changes made within this transaction
        /// </summary>
        /// <param name="transactionContext">The transaction context specific to database</param>
        void CancelTransaction(object transactionContext);        
        #endregion

        #region Register
        /// <summary>
        /// Subcribe a type of data object to this database
        /// </summary>
        void Register(Type objectType);

        /// <summary>
        /// Unsubcribe a type of data object from this database
        /// </summary>
        void Unregister(Type objectType);

        /// <summary>
        /// Gets all data types registered to this database
        /// </summary>
        Type[] RegisteredTypes
        { get;}
        #endregion

        #region Structuring
        /// <summary>
        /// Generate database structure specific to a single object type
        /// </summary>
        /// <param name="objectType">type of data object to generate</param>
        /// <param name="keepOldData">try to retain the existing data</param>
        void CreateStructure(Type objectType, bool keepOldData);

        /// <summary>
        /// Generate database structures (table, stored procedure, etc.) of all registered object types
        /// </summary>
        /// <param name="keepOldData">try to retain the existing data</param>
        void CreateStructure(bool keepOldData);
        #endregion

        #region Begin
        /// <summary>
        /// Gets a new transaction scope
        /// </summary>
        TransactionQuery Begin
        { get;}
        #endregion

        #region Insert
        /// <summary>
        /// Add new object(s) into database
        /// </summary>
        void InsertObjects(params object[] values);

        /// <summary>
        /// Add a collection of objects to database
        /// </summary>
        void InsertObjects(IList values);

        /// <summary>
        /// Add new objects into database
        /// </summary>
        InsertQuery Insert(params object[] values);

        /// <summary>
        /// Add a collection of objects to database
        /// </summary>
        InsertQuery Insert(IList values);
        #endregion

        #region Select
        /// <summary>
        /// Get object(s) matching the condition
        /// </summary>
        /// <param name="objectType">Type of object to query against</param>
        /// <param name="condition">Query criteria</param>
        /// <returns>A collection is always returned. If there are no object matches the condition, the collection is empty</returns>
        IList SelectObjects(Type objectType, Condition condition);

        /// <summary>
        /// Gets a new select query
        /// </summary>
        SelectQuery Select
        { get;}
        #endregion

        #region Update
        /// <summary>
        /// Update object(s) into database
        /// </summary>
        void UpdateObjects(params object[] values);

        /// <summary>
        /// Update a collection of objects to database
        /// </summary>
        void UpdateObjects(IList values);

        /// <summary>
        /// Gets a new update query
        /// </summary>
        UpdateQuery Update(params object[] values);

        /// <summary>
        /// Gets a new update query
        /// </summary>
        UpdateQuery Update(IList values);
        #endregion

        #region Delete
        /// <summary>
        /// Delete object(s) from database using their identifiers
        /// </summary>
        /// <param name="values">objects to delete</param>
        void DeleteObjects(params object[] values);

        /// <summary>
        /// Delete object(s) from database using their identifiers
        /// </summary>
        /// <param name="values">objects to delete</param>
        void DeleteObjects(IList values);

        /// <summary>
        /// Gets a new Delete query
        /// </summary>
        DeleteQuery Delete(params object[] values);

        /// <summary>
        /// Gets a new Delete query
        /// </summary>
        DeleteQuery Delete(IList values);

        /// <summary>
        /// Gets a new delete query
        /// </summary>
        DeleteQuery Delete();
        #endregion
    }
}
